ENVI::OpenRaster
The OpenRaster function method creates a new ENVIRaster from a file.
Example
; Launch the application
e = ENVI()
; Open an ENVI file and display it
file1 = FILEPATH('qb_boulder_msi', ROOT_DIR=e.ROOT_DIR, $
SUBDIR= ['data'])
raster1 = e.OpenRaster(file1)
view1 = e.GetView()
layer1 = view1.CreateLayer(raster1)
; Open a PNG file and display it
file2 = FILEPATH('avhrr.png', $
SUBDIRECTORY = ['examples','data'])
raster2 = e.OpenRaster(file2)
view2 = e.CreateView()
layer2 = view2.CreateLayer(raster2)
Syntax
Result = ENVI.OpenRaster(URI [, Keywords=value])
Return Value
This method returns a reference to an ENVIRaster. If the associated file is a NITF multiple image segment file, this method returns an array of ENVIRaster objects.
If the associated file is a MIE4NITF dataset, any image segments not associated with a raster series (camera) will be returned as an array of ENVIRaster objects. If the MIE4NITF dataset contains no image segments independent of a raster series, an "Unknown Dataset" error will be reported.
Arguments
URI
For local datasets, specify a scalar string that is a fully-qualified file path to a raster on disk.
For remote datasets, specify a string with the direct URL of the dataset. You can connect directly to the following:
- OGC server
- Cloud Optimized GeoTIFF file on an HTTP server or Amazon Web Services (AWS) S3 bucket.
- ArcGIS image service
- Jagwire server
The connection string is formatted the same as the URL field in the Open Remote Dataset dialog. See Using the Open Remote Dataset Dialog for examples of connection strings. If you connect to a remote dataset that requires authentication, you must set the USERNAME and PASSWORD keywords. Or, optionally set the /PROMPT_USER keyword to enter the user name and password.
OGC WCS
For OGC WCS, ENVI::OpenRaster loads the data using the highest WCS version that the server supports. You can set the version
keyword value as needed for best results. See the Remote Data Sources Background topic for the WCS versions that ENVI currently supports.
When using ENVI::OpenRaster to open WCS datasets, you can use the following debugging flags to see the HTTP calls and any possible errors. ENVI uses NCOM, which uses GDAL, to perform WCS HTTP calls.
- To enable debug logging of the HTTP calls that NCOM is making:
HTTP_IMPL_LOG_ON=1
HTTP_IMPL_LOG_DIR=c:\Logs
: This can be any folder you want. NCOM will write a file there namedhttp_impl_log.log
.
- To enable debug logging of the HTTP calls that GDAL is making:
CBL_DEBUG_on
CPL_LOG=c:\logs\cpl_log.txt
: This can be any filename.
Cloud Optimized GeoTIFF Files on S3 Buckets
The following code example shows how to access these files using ENVI::OpenRaster. It also shows how to use environment variables to configure S3 credentials.
; Start ENVI
e = ENVI()
; Specify a URL
s3url = 's3://MyDataFiles/MyCOGFile.tif'
; Specify S3 access information
access = 'my-access-key'
secret = 'my-secret-key'
; Set environment variables
setenv, 'AWS_ACCESS_KEY_ID=' + access
setenv, 'AWS_SECRET_ACCESS_KEY=' + secret
; Open the raster
raster = e.OpenRaster(s3url)
Keywords
Keywords are applied only during the initial creation of the object.
CUSTOM_TYPE
Use this keyword to define a custom file reader that will be used to open the raster. Set the keyword to a string with the name of the custom open procedure to call. You cannot use this keyword in conjunction with EXTERNAL_TYPE.
DATA_IGNORE_VALUE
Set this keyword to a pixel value that will be ignored when the raster is displayed. This overrides any data ignore values set in the metadata.
DATASET_INDEX
This keyword applies to the following file formats: ECRG, HDF5, Multi-page TIFF, NetCDF-4, NITF with multiple image segments, Proba-V, and SkySat-1. Specify a zero-based index number that corresponds to a specific raster dataset that you want to open within the file. For example, DATASET_INDEX=0 will open the first raster.
- Multi-page TIFF: Specify an index number with the specific page to open. For example, DATASET_INDEX=5 will open the sixth page.
- NITF: For files with multiple image segments, specify an index number corresponding to an individual image segment. DATASET_INDEX=0 will open the first image segment.
- Proba-V with radiometry:
- DATASET_INDEX=0: VNIR band
- DATASET_INDEX=1: SWIR band
- DATASET_INDEX=2: NDVI band
- DATASET_INDEX=3: Quality band
- Proba-V without radiometry:
- DATASET_INDEX=0: NDVI band
- DATASET_INDEX=1: Quality band
DATASET_NAME
This keyword applies to file formats with multiple datasets per file such as ECRG, generic HDF4, generic HDF5, Multi-page TIFF, NetCDF-3, NetCDF-4, and SkySat-1.
- Set this keyword to a string with the name of a raster dataset that you want to open within the file. Strings are case-sensitive.
- For NITF files with multiple image segments, use the DATASET_INDEX keyword instead.
- If you do not know the dataset names, use the Dataset Browser to open the files and obtain the names.
-
You do not need to use this keyword for the following data types because ENVI reads them natively; however, you can still specify a dataset name to open an individual dataset from the file:
- ASTER (HDF-EOS)
- Cosmo-SkyMed (HDF5)
- MODIS (HDF-EOS)
- EO-1 ALI and Hyperion (HDF4)
- MASTER (HDF4)
- Proba-V (HDF5)
- SeaWiFS (HDF4)
- SPOT Vegetation (HDF4)
- ResourceSat (HDF5)
- SSOT (HDF5)
- Suomi NPP VIIRS (HDF5)
- For Landsat-8, use one of the following strings to indicate a specific band group to open:
Multispectral
,Panchromatic
,Cirrus
,Thermal
, orQuality
. For example:
File = 'LC80430342015121LGN00_MTL.txt'
Raster = e.OpenRaster(File, DATASET_NAME='Multispectral')
You can also open Landsat-8 data by indicating the correct array element for a specific band group. See Metaspectral Datasets for more information.
HDF5 example
For HDF5 files, you can use the IDL H5_LIST routine to list the dataset names. This example uses an HDF5 file included in the ENVI+IDL installation. Set INSTALL_DIR
to the correct installation path and xx
to the correct version of IDL:
File = 'C:\Program Files\INSTALL_DIR\IDLxx\examples\data\hdf5_test.h5'
H5_LIST, File
IDL prints:
% Loaded DLM: HDF5.
file C:\Program Files\INSTALL_DIR\IDLxx\examples\data\hdf5_test.h5
dataset/2D int array H5T_INTEGER [50, 100]
dataset /A note H5T_STRING [2]
group /arrays
dataset /arrays/2D float array H5T_FLOAT [50, 100]
dataset /arrays/2D int array H5T_INTEGER [50, 100]
...
etc.
Then enter the following command:
Raster = e.OpenRaster(File, DATASET_NAME='/arrays/2D float array')
SkySat-1 example
Set the URI argument to a metadata file. Valid strings for DATASET_NAME include Panchromatic
, Multispectral
, or Pan Sharpened
.
File = 's01_20140315T161938Z_metadata.txt'
Raster = e.OpenRaster(File, DATASET_NAME='Panchromatic')
SkySat rasters open in their native spatial reference (typically RPC). They do not reproject as they would in the ENVI user interface.
Proba-V S10 example
Valid strings include VNIR
, SWIR
, NDVI
, and Quality
.
File = 'PROBAV_S10_TOC_X19Y03_20131121_333M_V001.h5'
Raster = e.OpenRaster(file, DATASET_NAME='NDVI')
ERROR
Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''
). If an error occurs and the routine is a function, then the function result will be undefined.
When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.
See Manage Errors for more information on error handling in ENVI programming.
EXTERNAL_TYPE
Use this keyword to open raster datasets in external file formats not natively supported by the ENVI software. Only use this keyword to open data files in the specific external file formats listed below—for all other raster datasets, this keyword should not be specified.
For example, to open a WorldView-2 dataset in TIFF format this keyword is not required; simply execute the OpenRaster method with the File argument. Consequently, the list of external file formats given below is not a comprehensive list of raster formats supported by the ENVI software.
Set this keyword to a string describing the type of the external file to open:
File Type String | Description |
---|---|
acres |
Australian Centre for Remote Sensing (ACRES) Canadian Centre for Remote Sensing (CCRS) Landsat and SPOT data |
ads40 |
Airborne Digital Sensor developed by Leica Geosystems |
alos |
Advanced Land Observing Satellite |
arcview |
ArcView raster format files that have the |
atsr |
Gridded Brightness Temperature (GBT), Gridded Browse (GBROWSE), and Gridded SST (GSST) data from ATSR-1 and ATSR-2 |
avhrr |
Advanced Very High Resolution Radiometer (AVHRR) |
avhrr_sharp |
European Space Agency SHARP data |
cadrg |
Compressed ARC Digitized Raster Graphics (CADRG) format |
cib |
Controlled Image Base (CIB) format |
cosmo-skymed |
COSMO-SkyMed radar format |
dmc |
ENVI reads and displays data from the UK-DMCSat-1, ALSAT-1, and NigeriaSat-1 satellites that are part of the DMC (Disaster Monitoring Constellation). |
dmsp_noaa |
NOAA Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS) format |
ecw |
Enhanced Compressed Wavelet |
envisat |
Environmental Satellite (Envisat) |
eo1_hdf |
EO-1 ALI or Hyperion data in HDF format |
eos_aster |
Earth Observing System (EOS) Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER) data |
eos_modis |
EOS Moderate Resolution Imaging Spectroradiometer (MODIS) data |
er_mapper |
ER mapper format |
erdas_lan |
ERDAS file (*.lan) |
eros_l1a |
Earth Resources Observation System 1A data |
eros_l1b |
ImageSat International EROS A Level 1B files |
ers |
European Remote Sensing Satellite-1 or -2 |
formosat-2 |
FORMOSAT-2 DIMAP (.dim) data |
irs_fast |
Indian Remote Sensing (IRS) data in Earth Observation Satellite Company (EOSAT) Fast format |
irs_super_structured |
IRS Super Structured data |
jers |
Japanese Earth Resources Satellite |
landsat_ceos |
European Space Agency CEOS Landsat TM data |
landsat_fast |
Landsat TM data in EOSAT Fast format |
landsat_hdf |
Landsat data in Hierarchical Data Format (HDF) |
landsat_mrlc |
Multi-Resolution Land Characteristic format for Landsat TM and DEM data |
landsat_nlaps |
National Landsat Archive Production System (NLAPS) format for Landsat TM and MSS data |
master |
MODIS/ASTER Simulator (MASTER) MAS-50 HDF data |
pci |
PCI Geomatics format ( |
pds |
Planetary Data System format |
pict |
QuickDraw Picture |
png |
Portable Network Graphics |
radarsat |
Canadian Radar Satellite data |
seawifs |
SeaWiFS data |
spot_cap_sisa |
SPOT 1A, 2A, and 1B data |
spot_geospot |
Reads the primary format for SPOT data. ArcView raster image files have a similar format specification. The GeoSPOT format is described in detail in documentation available from SPOT Image. |
spot_vegetation |
SPOT vegetation data |
srtm_dem |
Shuttle Radar Topography Mission Digital Elevation Model data |
srf |
Spectral Response Function. Engineering data that quantify the spectral response and sensitivity of detectors on an airborne or satellite sensor. The term SRF also refers to a data format that contains SRF data for particular sensors. |
tims |
Thermal Infrared Multispectral Scanner data |
topsar |
Raw AIRSAR Integrated Processor Data format (Cvv, incidence angle, correlation image, or DEM) |
usgs_doq |
USGS Digital Orthophoto Quadrangle data |
usgs_drg |
USGS Digital Raster Graphic data |
usgs_native_dem |
USGS Digital Elevation Model data |
usgs_sdts_dem |
USGS Spatial Data Transfer Standard |
xwd |
X Window Dump |
INTERLEAVE
This keyword only applies to three-dimensional datasets and specifies the interleave of the dataset when an interleave is not specifically defined in the file (as with HDF5 datasets). Set this keyword to one of the following strings:
String | Interleave | Data Array |
---|---|---|
bil | Band interleaved by line | [ncolumns, nbands, nrows] |
bip | Band interleaved by pixel | [nbands, ncolumns, nrows] |
bsq | Band sequential | [ncolumns, nrows, nbands] |
This keyword is optional and the default value 'bsq' is used if it is not set.
METADATA_OVERRIDE
Set this keyword to an ENVIRasterMetadata object (or an array of these objects, for files with multiple data groups). The metadata information for the newly created ENVIRaster will be taken from both the specified object and the ENVIRaster on disk (specified with URI).
If the ENVIRasterMetadata object specified by this keyword and the ENVIRaster specified by URI both have the same tag, the tag information from the ENVIRasterMetadata object will take precedence. Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.
If the ENVIRasterMetadata object contains the string 'read procedures
,' then the ENVIRaster is opened using a custom read routine.
The DATA_IGNORE_VALUE keyword takes precedence over the METADATA_OVERRIDE keyword.
For NPP VIIRS files, only the I, M, DNB, or NCC bands (rasters) can be overridden. Metadata override is not allowed for the Latitude, Longitude, Height, or Quality bands.
PASSWORD
Set this keyword to a string with a valid password for opening a remote dataset that requires authentication.
PROMPT_USER
Set this keyword in an interactive session (not for use with batch mode) if you want ENVI to prompt you for certain input parameters instead of performing default actions.
If you set the PROMPT_USER keyword and open an NPP VIIRS dataset, the NPP VIIRS Parameters dialog will appear for you to select calibration options. If you do not set this keyword and you open an NPP VIIRS dataset, the dataset will be calibrated to radiance, by default.
SENSOR_MODEL
Specify a string with the sensor model to use. An example is 'RSM'
(replacement sensor model). To get a list of available SENSOR_MODEL values for the raster, use ENVINITFQuerySensorModels.
This keyword is only available with the ENVI Department of Defense (DoD) plug-in. This is a separate package that provides additional support in ENVI for data formats and sensor models that are commonly used by customers in the U.S. defense and intelligence community. It includes features such as Mensuration Services Program (MSP) integration, Community Sensor Model (CSM) support, TFRD, and additional NITF capabilities. Contact your sales representative for more information.
If the MSP Sensor Model Selection preference has been set to "Enable User Selection" and the SENSOR_MODEL keyword has not been set, then SENSOR_MODEL will default to using "Use MSP Default."
SPATIALREF_OVERRIDE
Set this keyword to an ENVINITFCSMRasterSpatialRef, ENVIPseudoRasterSpatialRef, ENVIRPCRasterSpatialRef, or ENVIStandardRasterSpatialRef object (or an array of these objects, for files with multiple data groups). The spatial reference information for the newly created ENVIRaster will be taken from the specified object (or array of objects), and not from the associated raster data file(s). Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.
If the ENVIRaster contains a combination of standard and auxiliary (RPCs or pseudo) map information, and you set SPATIALREF_OVERRIDE to an ENVIStandardRasterSpatialRef object, the original auxiliary map information will be lost.
Note: You cannot set this keyword to an object of type 'arbitrary'. Also, this keyword is not supported when opening a file using the EXTERNAL_TYPE keyword.
TEMPLATE
Set this keyword to a string with the name of a custom XML template used to open generic HDF4, generic HDF5 , NetCDF-3, and NetCDF-4 datasets. Creating and restoring templates can be helpful when you want to build the same raster and metadata structure from several source files. See Work with Templates for instructions on creating templates. Save templates to the directory specified by the Custom Code Directory preference. If you set this keyword, you cannot also set the DATASET_NAME keyword.
The following example code shows how to open an AVHRR sea surface temperature (SST) dataset using a template that resides in the Custom Code Directory.
file = '2014_290_1122_n19_eb.hdf'
raster = e.OpenRaster(file, TEMPLATE='NOAA-19 AVHRR SST')
TERRAIN_SOURCE (Init)
Specify a string with the terrain source to use:
-
Best
: Used by default if a terrain source is not specified -
DTED0
-
DTED1
-
DTED2
-
Reference Point
-
SRTM0
-
SRTM1
-
Terrain Base
This keyword is only available with the ENVI Department of Defense (DoD) plug-in.
TIME_OVERRIDE
Set this keyword to an ENVITime object (or an array of these objects, for files with multiple data groups). The time information for the newly created ENVIRaster will be taken from the specified object (or array of objects), and not from the associated raster data file(s). Although this process only happens in memory, the information will be persisted to a header file if the ENVIRaster::WriteMetadata method is called.
USER_HEIGHT (Init)
Specify a height value (in meters) to use for all file-to-map and map-to-file coordinate conversions for the spatial reference.
This keyword is only available with the ENVI Department of Defense (DoD) plug-in.
USERNAME
Set this keyword to a string with a valid user name for opening a remote dataset that requires authentication.
UVALUE
Use this keyword only in conjunction with the CUSTOM_TYPE keyword to indicate that the raster should be opened with a custom open procedure. The value set with this keyword will be passed into the custom open procedure's UVALUE keyword. If the custom open procedure does not accept the UVALUE keyword, then it will be ignored.
Version History
ENVI 5 |
Introduced |
ENVI 5.0.2 |
Added new keywords: CUSTOM_TYPE, TIME_OVERRIDE, and UVALUE |
ENVI 5.1 |
Added new keywords: DATASET and INTERLEAVE Added |
ENVI 5.2.1 |
Bitmap ( |
ENVI 5.4 |
Added generic HDF4 and NetCDF-3 as supported formats for the DATASET_NAME and TEMPLATE keywords. Added The following strings for the EXTERNAL_TYPE keyword are obsolete because ENVI::OpenRaster automatically supports these formats: |
ENVI 5.5.1 |
Added SENSOR_MODEL keyword |
ENVI 5.5.3 |
Added USER_HEIGHT keyword |
ENVI 5.6.1 |
Added URI support for OGC WFS and WMTS datasets, cloud-optimized GeoTIFF files, and AWS S3 buckets |
ENVI 5.6.2 |
Added TERRAIN_SOURCE keyword |
ENVI 5.7 | Deprecated sicd as an EXTERNAL_TYPE file type string. SICD support has been added to ENVI. |
API Version
4.2
See Also
ENVI function, ENVI::GetView, ENVIView::CreateLayer, ENVIRaster